feat(agents): add Agents (experimental) to Grid API spec#430
Merged
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
Contributor
✱ Stainless preview buildsThis PR will update the kotlin openapi python typescript
|
Introduces two new tag groups:
- Agent Management: platform-scoped CRUD, policy, device codes, approvals (BasicAuth)
- Agent Operations: agent-scoped payments, quotes, transfers, external accounts (AgentAuth)
New schemas (18): Agent, AgentCreateRequest/Response, AgentUpdateRequest,
AgentListResponse, AgentPolicy, AgentPolicyUpdateRequest, AgentPermission,
AgentExecutionMode, AgentSpendingLimits/Update, AgentApprovalThresholds,
AgentAccountRestrictions/Rule, AgentUsage, AgentDeviceCode,
AgentDeviceCodeStatusResponse, AgentDeviceCodeRedeemResponse
New endpoints (19):
- POST/GET /agents, GET /agents/approvals
- GET/PATCH/DELETE /agents/{agentId}, PATCH /agents/{agentId}/policy
- POST /agents/{agentId}/device-codes (regenerate)
- GET /agents/device-codes/{code}/status, POST .../redeem
- POST /agents/{agentId}/transactions/{transactionId}/approve|reject
- GET /agents/me, GET/POST /agents/me/transactions, /quotes, /external-accounts
- POST /agents/me/transfer-in|out, /quotes/{quoteId}/execute
Also: adds agentId to Transaction schema; updates approvals-and-audit.mdx
and policies-and-permissions.mdx to match spec field names and shapes;
adds sidebar icons for both groups in style.css
…fy type rendering
…t Mintlify type rendering" This reverts commit e768ff3.
…action fields - Add agent_client_id/agent_client_secret opts to stainless.yml client_settings so Stainless can resolve the AgentAuth security scheme (fixes SchemeNotFound error) - Fix approvals-and-audit.mdx to use correct OutgoingTransaction field names: sentAmount/receivedAmount (CurrencyAmount objects) instead of sendingAmount, and correct type discriminator value OUTGOING instead of OUTGOING_PAYMENT
Replace HTTP Basic (clientId + clientSecret) with a single Bearer access token for agent authentication. Simpler for agent software to configure and store. - AgentAuth security scheme: basic → bearer - AgentDeviceCodeRedeemResponse: drop clientId/clientSecret, add accessToken - stainless.yml: replace agent_client_id/secret opts with single agent_access_token
All agent-initiated operations now return an AgentAction rather than a raw
Quote or Transaction, giving the platform a consistent object to approve/reject
with its own status lifecycle (PENDING_APPROVAL → APPROVED/REJECTED/FAILED).
- New schemas: AgentAction, AgentActionStatus, AgentActionType,
AgentActionListResponse, AgentTransferDetails, AgentActionRejectRequest
- execute/transfer-out/transfer-in endpoints now return AgentAction
- GET /agents/approvals returns AgentActionListResponse (not TransactionListResponse)
- Approval endpoints moved from /agents/{id}/transactions/{id}/approve|reject
to /agents/{id}/actions/{id}/approve|reject
- New agent-scoped: GET /agents/me/actions and GET /agents/me/actions/{actionId}
for polling approval decisions
k15z
force-pushed
the
feat/agents-experimental
branch
from
eec6e60 to
3c0839c
Compare
Maps all agent management endpoints explicitly to prevent stale guessed-config errors after the approve/reject paths moved from /transactions/ to /actions/.
Update to reflect current API: AgentAction objects (not Transactions), PENDING_APPROVAL status, AGENT_ACTION.PENDING_APPROVAL webhook flow, new approve/reject endpoint paths, quote/transferDetails fields, and FAILED state for expired quotes.
pengying
approved these changes
May 1, 2026
Contributor
Greptile SummaryThis PR adds the Agents (experimental) surface to the Grid API spec: 22 new endpoint paths, 24 new schemas, a device-code installation flow,
Confidence Score: 3/5Two P1 documentation errors — a nonexistent approval endpoint URL and a nonexistent status value — need to be fixed before this ships to integrators. Two P1 findings are present: a wrong endpoint URL propagated across three operation descriptions that would cause integrators to call a 404 path, and a
|
| Filename | Overview |
|---|---|
| openapi/paths/agents/agents_me_transfer-in.yaml | New transfer-in endpoint for agents; description references a nonexistent approval endpoint URL (/agents/{agentId}/transactions/{transactionId}/approve instead of /agents/{agentId}/actions/{actionId}/approve) |
| openapi/paths/agents/agents_me_transfer-out.yaml | New transfer-out endpoint for agents; same stale approval URL issue as transfer-in description |
| openapi/paths/agents/agents_me_quotes_{quoteId}_execute.yaml | New execute-quote endpoint for agents; description references nonexistent /agents/{agentId}/transactions/{transactionId}/approve approval endpoint |
| mintlify/global-accounts/agents/approvals-and-audit.mdx | Approval lifecycle docs updated with accurate webhook flow and field reference; step 8 incorrectly references a COMPLETED status that does not exist in AgentActionStatus |
| openapi/components/schemas/agents/AgentApprovalThresholds.yaml | New schema for approval thresholds; currency described as required when amount is set but the constraint is not enforced in the schema |
| openapi/components/schemas/agents/AgentAction.yaml | Core AgentAction schema with correct status references and embedded quote/transfer details for approval UI rendering; well structured |
| openapi/components/schemas/agents/AgentActionStatus.yaml | Defines four terminal/non-terminal statuses: PENDING_APPROVAL, APPROVED, REJECTED, FAILED; note that COMPLETED (referenced in docs) is absent by design — APPROVED is the completion state |
| openapi/openapi.yaml | Root spec additions: AgentAuth security scheme, tag descriptions, and 22 new path entries; literal paths (me, approvals, device-codes) correctly precede the {agentId} parameter path |
| openapi/webhooks/agent-action.yaml | New webhook for AGENT_ACTION.PENDING_APPROVAL; includes full AgentAction example payload with webhook signature verification instructions |
| .stainless/stainless.yml | Adds agents resource with all methods, subresources, and agent_access_token client setting for GRID_AGENT_ACCESS_TOKEN env var; clean structure |
| mintlify/global-accounts/agents/policies-and-permissions.mdx | Updated permissions table and policy example to match actual enum values and correct field names; clean alignment with spec |
Sequence Diagram
sequenceDiagram
participant P as Platform Backend
participant G as Grid API
participant A as Agent Software
participant C as Customer App
P->>G: POST /agents (BasicAuth)
G-->>P: AgentCreateResponse + DeviceCode
A->>G: POST /agents/device-codes/{code}/redeem (no auth)
G-->>A: accessToken (gat_...)
P->>G: GET /agents/device-codes/{code}/status (BasicAuth)
G-->>P: { redeemed: true }
Note over A,G: Agent Operations (AgentAuth Bearer)
A->>G: POST /agents/me/quotes
G-->>A: Quote
A->>G: POST /agents/me/quotes/{quoteId}/execute
G-->>A: AgentAction { status: PENDING_APPROVAL }
G-->>P: Webhook: AGENT_ACTION.PENDING_APPROVAL
P->>C: Push notification
C->>P: Approve / Reject
P->>G: POST /agents/{agentId}/actions/{actionId}/approve (BasicAuth)
G-->>P: AgentAction { status: APPROVED }
Note over A,G: Agent polls for decision
A->>G: GET /agents/me/actions/{actionId}
G-->>A: AgentAction { status: APPROVED, transaction: {...} }
Prompt To Fix All With AI
Fix the following 3 code review issues. Work through them one at a time, proposing concise fixes.
---
### Issue 1 of 3
openapi/paths/agents/agents_me_transfer-in.yaml:8-10
**Wrong approval endpoint referenced in description**
The description points to `POST /agents/{agentId}/transactions/{transactionId}/approve`, but no such endpoint exists in this spec. The correct approval endpoint is `POST /agents/{agentId}/actions/{actionId}/approve`. This same stale URL appears in three places: here, `agents_me_transfer-out.yaml` (lines 8–10), and `agents_me_quotes_{quoteId}_execute.yaml` (line 17). Integrators following the embedded docs would call a 404-bound path and be unable to approve pending actions.
```suggestion
If the agent's policy requires approval for this amount, the transaction will be
created in a pending state and must be approved by the platform via
`POST /agents/{agentId}/actions/{actionId}/approve`.
```
### Issue 2 of 3
mintlify/global-accounts/agents/approvals-and-audit.mdx:29
**`COMPLETED` status does not exist in the spec**
Step 8 describes the `AgentAction` transitioning to `APPROVED`, then `COMPLETED`. However, `AgentActionStatus.yaml` only defines four values: `PENDING_APPROVAL`, `APPROVED`, `REJECTED`, and `FAILED` — there is no `COMPLETED` terminal state. `APPROVED` is itself the completion state ("execution is in progress or completed" per the schema description). Documenting a nonexistent status here will cause integrators to poll for a terminal state that never arrives.
```suggestion
8. Grid executes the action and the `AgentAction` transitions to `APPROVED` — or `REJECTED` if declined. If the underlying quote expires before approval is granted, the action transitions to `FAILED` instead.
```
### Issue 3 of 3
openapi/components/schemas/agents/AgentApprovalThresholds.yaml:8-10
**Conditional `currency` requirement not enforced by schema**
The description says `currency` is "Required when amount is set," but the schema has no `required` array and no `if/then` constraint to enforce this. A client could send `{"amount": 100000}` without a `currency`, which would be semantically invalid — Grid couldn't know what denomination the threshold is in. Consider adding an `if/then` constraint:
```yaml
if:
required: [amount]
properties:
amount:
not:
type: 'null'
then:
required: [currency]
```
Reviews (1): Last reviewed commit: "Merge branch 'main' into feat/agents-exp..." | Re-trigger Greptile
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
Comment on lines
+8
to
+10
| If the agent's policy requires approval for this amount, the transaction will be | ||
| created in a pending state and must be approved by the platform via | ||
| `POST /agents/{agentId}/transactions/{transactionId}/approve`. |
Contributor
There was a problem hiding this comment.
The description points to POST /agents/{agentId}/transactions/{transactionId}/approve, but no such endpoint exists in this spec. The correct approval endpoint is POST /agents/{agentId}/actions/{actionId}/approve. This same stale URL appears in three places: here, agents_me_transfer-out.yaml (lines 8–10), and agents_me_quotes_{quoteId}_execute.yaml (line 17). Integrators following the embedded docs would call a 404-bound path and be unable to approve pending actions.
Suggested change
| If the agent's policy requires approval for this amount, the transaction will be | |
| created in a pending state and must be approved by the platform via | |
| `POST /agents/{agentId}/transactions/{transactionId}/approve`. | |
| If the agent's policy requires approval for this amount, the transaction will be | |
| created in a pending state and must be approved by the platform via | |
| `POST /agents/{agentId}/actions/{actionId}/approve`. |
Prompt To Fix With AI
This is a comment left during a code review.
Path: openapi/paths/agents/agents_me_transfer-in.yaml
Line: 8-10
Comment:
**Wrong approval endpoint referenced in description**
The description points to `POST /agents/{agentId}/transactions/{transactionId}/approve`, but no such endpoint exists in this spec. The correct approval endpoint is `POST /agents/{agentId}/actions/{actionId}/approve`. This same stale URL appears in three places: here, `agents_me_transfer-out.yaml` (lines 8–10), and `agents_me_quotes_{quoteId}_execute.yaml` (line 17). Integrators following the embedded docs would call a 404-bound path and be unable to approve pending actions.
```suggestion
If the agent's policy requires approval for this amount, the transaction will be
created in a pending state and must be approved by the platform via
`POST /agents/{agentId}/actions/{actionId}/approve`.
```
How can I resolve this? If you propose a fix, please make it concise.
| 5. Your app shows the customer the requested amount, accounts, and reason. | ||
| 6. The customer approves or rejects from that trusted surface. | ||
| 7. Your backend calls `POST /agents/{agentId}/actions/{actionId}/approve` or `.../reject`. | ||
| 8. Grid executes the action and the `AgentAction` transitions to `APPROVED`, then `COMPLETED` — or `REJECTED` if declined. |
Contributor
There was a problem hiding this comment.
COMPLETED status does not exist in the spec
Step 8 describes the AgentAction transitioning to APPROVED, then COMPLETED. However, AgentActionStatus.yaml only defines four values: PENDING_APPROVAL, APPROVED, REJECTED, and FAILED — there is no COMPLETED terminal state. APPROVED is itself the completion state ("execution is in progress or completed" per the schema description). Documenting a nonexistent status here will cause integrators to poll for a terminal state that never arrives.
Suggested change
| 8. Grid executes the action and the `AgentAction` transitions to `APPROVED`, then `COMPLETED` — or `REJECTED` if declined. | |
| 8. Grid executes the action and the `AgentAction` transitions to `APPROVED` — or `REJECTED` if declined. If the underlying quote expires before approval is granted, the action transitions to `FAILED` instead. |
Prompt To Fix With AI
This is a comment left during a code review.
Path: mintlify/global-accounts/agents/approvals-and-audit.mdx
Line: 29
Comment:
**`COMPLETED` status does not exist in the spec**
Step 8 describes the `AgentAction` transitioning to `APPROVED`, then `COMPLETED`. However, `AgentActionStatus.yaml` only defines four values: `PENDING_APPROVAL`, `APPROVED`, `REJECTED`, and `FAILED` — there is no `COMPLETED` terminal state. `APPROVED` is itself the completion state ("execution is in progress or completed" per the schema description). Documenting a nonexistent status here will cause integrators to poll for a terminal state that never arrives.
```suggestion
8. Grid executes the action and the `AgentAction` transitions to `APPROVED` — or `REJECTED` if declined. If the underlying quote expires before approval is granted, the action transitions to `FAILED` instead.
```
How can I resolve this? If you propose a fix, please make it concise.
Comment on lines
+8
to
+10
| type: string | ||
| description: ISO 4217 currency code that the amount threshold is denominated in. Required when amount is set. | ||
| example: USD |
Contributor
There was a problem hiding this comment.
currency requirement not enforced by schema
The description says currency is "Required when amount is set," but the schema has no required array and no if/then constraint to enforce this. A client could send {"amount": 100000} without a currency, which would be semantically invalid — Grid couldn't know what denomination the threshold is in. Consider adding an if/then constraint:
if:
required: [amount]
properties:
amount:
not:
type: 'null'
then:
required: [currency]Prompt To Fix With AI
This is a comment left during a code review.
Path: openapi/components/schemas/agents/AgentApprovalThresholds.yaml
Line: 8-10
Comment:
**Conditional `currency` requirement not enforced by schema**
The description says `currency` is "Required when amount is set," but the schema has no `required` array and no `if/then` constraint to enforce this. A client could send `{"amount": 100000}` without a `currency`, which would be semantically invalid — Grid couldn't know what denomination the threshold is in. Consider adding an `if/then` constraint:
```yaml
if:
required: [amount]
properties:
amount:
not:
type: 'null'
then:
required: [currency]
```
How can I resolve this? If you propose a fix, please make it concise.
shreyav
approved these changes
May 1, 2026
2 tasks
pengying
pushed a commit
that referenced
this pull request
May 1, 2026
…status (#433) ## Summary - **Auth scheme**: Added `AgentAuth` to the global `security` array in `openapi/openapi.yaml`. Per Stainless docs, the top-level security array determines which schemes the SDK client supports — without it, the Stainless `merge` step was failing, which is why the published docs at grid.lightspark.com never reflected the agents endpoints after #430 merged. - **Stale paths**: Three agent endpoint descriptions still referenced the old `POST /agents/{agentId}/transactions/{transactionId}/approve` path. Updated to `POST /agents/{agentId}/actions/{actionId}/approve`. - **Phantom status**: `approvals-and-audit.mdx` step 8 documented a `COMPLETED` terminal state that does not exist in `AgentActionStatus`. `APPROVED` is the terminal success state. Removed to prevent integrators from polling for a state that never arrives. ## Test plan - [ ] Stainless `merge` check passes (unblocks published docs update) - [ ] Verify agent endpoints appear in published sidebar after merge
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds Agents (experimental) to the Grid API — a surface for connecting AI agents to Global Accounts with managed policy, approval flows, and delegated credentials.
New API surface
Agent Management (platform-scoped,
BasicAuth)POST /agents— create an agent with name, customer ID, and policy; returns agent + device code for installationGET /agents— list agents with filters:customerId,isPaused,isConnected, date ranges, paginationGET /agents/{agentId}— retrieve a single agentPATCH /agents/{agentId}— update name or pause/unpauseDELETE /agents/{agentId}— permanently deletePATCH /agents/{agentId}/policy— partial-update policy (permissions, execution mode, spending limits, account restrictions, approval thresholds)POST /agents/{agentId}/device-codes— regenerate a device code (409 if agent already connected)GET /agents/device-codes/{code}/status— poll for installation completionPOST /agents/device-codes/{code}/redeem— redeem device code for a Bearer access token (no auth)GET /agents/approvals— platform-scoped list of pendingAgentActions, withagentId/customerIdfiltersPOST /agents/{agentId}/actions/{actionId}/approve— approve a pending agent actionPOST /agents/{agentId}/actions/{actionId}/reject— reject a pending agent action (optional reason)Agent Operations (agent-scoped,
AgentAuthBearer token)GET /agents/me— agent reads its own profile and policyGET /agents/me/actions/GET /agents/me/actions/{actionId}— poll approval status of submitted actionsGET /agents/me/internal-accounts— list customer's internal accounts (filtered by currency/type)GET /agents/me/transactions/GET /agents/me/transactions/{id}— transaction historyPOST /agents/me/quotes/GET /agents/me/quotes/{quoteId}— quote creation and retrievalPOST /agents/me/quotes/{quoteId}/execute— submit quote execution as anAgentActionPOST /agents/me/transfer-in/POST /agents/me/transfer-out— submit transfers asAgentActionsGET /agents/me/external-accounts/POST/GET /{id}/DELETE /{id}— manage external accountsAgentAction approval model
All agent-initiated operations return an
AgentAction(not a raw transaction or quote), giving the platform a consistent object to approve/reject with its own status lifecycle:PENDING_APPROVAL → APPROVED | REJECTED | FAILEDThe
AgentActionembeds the full quote or transfer details, so approval UIs can render without a second API call. TheFAILEDstate handles quote expiry — if approval takes too long and the underlying quote expires, the action transitions toFAILEDrather than leaving it in limbo.New webhook
AGENT_ACTION.PENDING_APPROVAL— fired when an agent submits an action requiring approval. Payload contains the fullAgentActionso platforms can immediately send a push notification to the customer.New schemas (24)
Agent management:
Agent,AgentCreateRequest,AgentCreateResponse,AgentUpdateRequest,AgentListResponse,AgentPolicy,AgentPolicyUpdateRequest,AgentPermission,AgentExecutionMode,AgentSpendingLimits,AgentSpendingLimitsUpdate,AgentApprovalThresholds,AgentAccountRestrictions,AgentAccountRule,AgentUsage,AgentDeviceCode,AgentDeviceCodeStatusResponse,AgentDeviceCodeRedeemResponseApproval flow:
AgentAction,AgentActionStatus,AgentActionType,AgentActionListResponse,AgentTransferDetails,AgentActionRejectRequestWebhook:
AgentActionWebhookOther spec changes
Transactiongains optionalagentIdfieldAgentAuthsecurity scheme added (type: http, scheme: bearer)WebhookTypeenum extended withAGENT_ACTION.PENDING_APPROVAL.stainless/stainless.yml—agent_access_tokenopt added (GRID_AGENT_ACCESS_TOKENenv var)Docs (3 new pages)
mintlify/global-accounts/agents/overview.mdx— feature overview, system flow, design principlesmintlify/global-accounts/agents/policies-and-permissions.mdx— permissions reference, execution modes, spending limits, approval thresholds, full policy examplemintlify/global-accounts/agents/approvals-and-audit.mdx— approval lifecycle, outcomes, activity records, pause/revoke guidanceTest plan
make lintexits 0make buildregenerates bundle without errorsSchemeNotFounderrors)make mint)AgentActionstatus lifecycle against server implementationAgentAuthBearer scheme aligns with server implementationaccessTokenformat/prefix (gat_...) matches server implementationAGENT_ACTION.PENDING_APPROVALwebhook delivery matches server behavior